---
sidebar_label: JWT/OIDC
description: |-
  This is the API documentation for the OpenBao JWT/OIDC authentication
  method plugin.
---

# JWT/OIDC auth method (API)

:::warning

**Note**: This engine can use external X.509 certificates as part of TLS or signature validation.
   Verifying signatures against X.509 certificates that use SHA-1 is deprecated and is no longer
   usable without a workaround. See the
   [deprecation FAQ](/docs/deprecation/faq#q-what-is-the-impact-of-removing-support-for-x-509-certificates-with-signatures-that-use-sha-1)
   for more information.

:::

This is the API documentation for the OpenBao JWT/OIDC auth method
plugin. To learn more about the usage and operation, see the
[OpenBao JWT/OIDC method documentation](/docs/auth/jwt).

This documentation assumes the plugin method is mounted at the
`/auth/jwt` path in OpenBao. Since it is possible to enable auth methods
at any location, please update your API calls accordingly.

## Configure

Configures the validation information to be used globally across all roles. One
(and only one) of `oidc_discovery_url`, `jwks_url`, and `jwt_validation_pubkeys` must be
set.

| Method | Path               |
| :----- | :----------------- |
| `POST` | `/auth/jwt/config` |

### Parameters

- `oidc_discovery_url` `(string: <optional>)` - The OIDC Discovery URL, without any .well-known component (base path). Cannot be used with "jwks_url" or "jwt_validation_pubkeys".
- `oidc_discovery_ca_pem` `(string: <optional>)` - The contents of a CA certificate or chain of certificates, in PEM format, to use to validate connections to the OIDC Discovery URL. If not set, system certificates are used.
- `oidc_client_id` `(string: <optional>)` - The OAuth Client ID from the provider for OIDC roles.
- `oidc_client_secret` `(string: <optional>)` - The OAuth Client Secret from the provider for OIDC roles.
- `oidc_response_mode` `(string: <optional>)` - The response mode to be used in the OAuth2 request. Allowed values are "query" and "form_post". Defaults to "query".
- `oidc_response_types` `(comma-separated string, or array of strings: <optional>)` - The response types to request. Allowed values are "code" and "id_token". Defaults to "code".
  Note: "id_token" may only be used if "oidc_response_mode" is set to "form_post".
- `jwks_url` `(string: <optional>)` - JWKS URL to use to authenticate signatures. Cannot be used with "oidc_discovery_url" or "jwt_validation_pubkeys".
- `jwks_ca_pem` `(string: <optional>)` - The contents of a CA certificate or chain of certificates, in PEM format, to use to validate connections to the JWKS URL. If not set, system certificates are used.
- `jwt_validation_pubkeys` `(comma-separated string, or array of strings: <optional>)` - A list of PEM-encoded public keys to use to authenticate signatures locally. Cannot be used with "jwks_url" or "oidc_discovery_url".
- `bound_issuer` `(string: <optional>)` - The value against which to match the `iss` claim in a JWT.
- `jwt_supported_algs` `(comma-separated string, or array of strings: <optional>)` - A list of supported signing algorithms. Defaults to [RS256] for OIDC roles. Defaults to all [available algorithms](https://github.com/hashicorp/cap/blob/main/jwt/algs.go) for JWT roles.
- `default_role` `(string: <optional>)` - The default role to use if none is provided during login.
- `provider_config` `(map: <optional>)` - Configuration options for provider-specific handling. Providers with specific handling include: Azure, Google, SecureAuth, IBM ISAM. The options are described in each provider's section in [OIDC Provider Setup](/docs/auth/jwt/oidc-providers).
- `namespace_in_state` `(bool: true)` - Pass namespace in the OIDC state parameter instead of as a separate query parameter. With this setting, the allowed redirect URL(s) in OpenBao and on the provider side should not contain a namespace query parameter. This means only one redirect URL entry needs to be maintained on the provider side for all vault namespaces that will be authenticating against it. Defaults to true for new configs.

### Sample payload

```json
{
  "oidc_discovery_url": "https://myco.auth0.com/",
  "bound_issuer": "https://myco.auth0.com/"
}
```

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/auth/jwt/config
```

## Read config

Returns the previously configured config.

| Method | Path               |
| :----- | :----------------- |
| `GET`  | `/auth/jwt/config` |

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    https://127.0.0.1:8200/v1/auth/jwt/config
```

### Sample response

```json
{
  "data":{
    "oidc_discovery_url": "https://myco.auth0.com/",
    "oidc_discovery_ca_pem": [],
    "bound_issuer": "https://myco.auth0.com/",
    "jwt_validation_pubkeys": []
  },
  ...
}
```

## Create/Update role

Registers a role in the method. Role types have specific entities
that can perform login operations against this endpoint. Constraints specific
to the role type must be set on the role. These are applied to the authenticated
entities attempting to login. At least one of the bound values must be set.

| Method | Path                   |
| :----- | :--------------------- |
| `POST` | `/auth/jwt/role/:name` |

### Parameters

- `name` `(string: <required>)` - Name of the role.
- `role_type` `(string: <optional>)` - Type of role, either "oidc" (default) or "jwt".
- `bound_audiences` `(array: <optional>)` - List of `aud` claims to match against.
  Any match is sufficient. For "jwt" roles, at least one of `bound_audiences`, `bound_subject`,
  `bound_claims` or `token_bound_cidrs` is required. Optional for "oidc" roles.
- `user_claim` `(string: <required>)` - The claim to use to uniquely identify
  the user; this will be used as the name for the Identity entity alias created
  due to a successful login. The claim value must be a string.
- `user_claim_json_pointer` `(bool: false)` - Specifies if the `user_claim` value uses
  [JSON pointer](/docs/auth/jwt#claim-specifications-and-json-pointer) syntax for
  referencing claims. By default, the `user_claim` value will not use JSON pointer.
- `clock_skew_leeway` `(int or string: <optional>)` - The amount of leeway to add to all claims to
  account for clock skew, in seconds. Defaults to `60` seconds if set to `0` and can be disabled
  if set to `-1`. Accepts an integer number of seconds, or a Go duration format string. Only applicable
  with "jwt" roles.
- `expiration_leeway` `(int or string: <optional>)` - The amount of leeway to add to expiration (`exp`) claims to
  account for clock skew, in seconds. Defaults to `150` seconds if set to `0` and can be disabled
  if set to `-1`. Accepts an integer number of seconds, or a Go duration format string. Only applicable
  with "jwt" roles.
- `not_before_leeway` `(int or string: <optional>)` - The amount of leeway to add to not before (`nbf`) claims to
  account for clock skew, in seconds. Defaults to `150` seconds if set to `0` and can be disabled
  if set to `-1`. Accepts an integer number of seconds, or a Go duration format string. Only applicable
  with "jwt" roles.
- `bound_subject` `(string: <optional>)` - If set, requires that the `sub`
  claim matches this value.
- `bound_claims` `(map: <optional>)` - If set, a map of claims (keys) to match against respective claim values (values).
  The expected value may be a single string or a list of strings. The interpretation of the bound
  claim values is configured with `bound_claims_type`. Keys support [JSON pointer](/docs/auth/jwt#claim-specifications-and-json-pointer)
  syntax for referencing claims.
- `bound_claims_type` `(string: "string")` - Configures the interpretation of the bound_claims values.
  If `"string"` (the default), the values will treated as string literals and must match exactly.
  If set to `"glob"`, the values will be interpreted as globs, with `*` matching any number of
  characters.
- `groups_claim` `(string: <optional>)` - The claim to use to uniquely identify
  the set of groups to which the user belongs; this will be used as the names
  for the Identity group aliases created due to a successful login. The claim
  value must be a list of strings. Supports [JSON pointer](/docs/auth/jwt#claim-specifications-and-json-pointer)
  syntax for referencing claims.
- `claim_mappings` `(map: <optional>)` - If set, a map of claims (keys) to be copied to
  specified metadata fields (values). Keys support [JSON pointer](/docs/auth/jwt#claim-specifications-and-json-pointer)
  syntax for referencing claims.
- `oauth2_metadata` `(list: <optional>` - If set, a list of token types
  that come from the OIDC provider to return in metadata.
  The types can be any of `access_token`, `id_token`, or `refresh_token`,
  and when present the values are returned in corresponding metadata fields
  with `oauth2_` prefixes as names.
  Note that these tokens can potentially include sensitive security
  information so use caution before enabling them and make sure the client
  treats the information in a safe manner.
- `oidc_scopes` `(list: <optional>)` - If set, a list of OIDC scopes to be used with an OIDC role.
  The standard scope "openid" is automatically included and need not be specified.
- `allowed_redirect_uris` `(list: <required except in device callback mode>)` - The list of allowed values for redirect_uri
  during OIDC logins.
- `callback_mode` `(string: <optional>)` - The callback mode from the OIDC provider, either "client" (the default)
  to call back to the client,
  "direct" to call back to the OpenBao server,
  or "device" for device flow which has no callback.
- `poll_interval` `(int: <optional>)` - Poll interval in seconds for device
  and direct callback modes, default value from Authorization Server for
  device flow, or '5'.
- `verbose_oidc_logging` `(bool: false)` - Log received OIDC tokens and claims when debug-level
  logging is active. Not recommended in production since sensitive information may be present
  in OIDC responses.
- `max_age` `(int or string: <optional>)` - Specifies the allowable elapsed time in seconds since the last
  time the user was actively authenticated with the OIDC provider. If set, the `max_age` request parameter
  will be included in the authentication request. See [AuthRequest](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest)
  for additional details. Accepts an integer number of seconds, or a Go duration format string.
- `token_policies_template_claims` `(bool: false)` - When enabled, allows entries in
  `token_policies` to contain templates which are computed with all claims on the
  underlying JWT or OIDC ID token. This uses [`sdk/helper/template`](https://pkg.go.dev/github.com/openbao/openbao/sdk/v2@v2.0.1/helper/template)
  which is based on [`text/template`](https://pkg.go.dev/text/template) for templating.
  Templates which evaluate to the empty string are removed and all referenced claims
  must exist on the authenticating token. See [examples](#acl-policy-templating-examples)
  below.

@include 'tokenfields.mdx'

### ACL policy templating examples

If the given JWT contains custom claims for `project_id`, `environment`, and
`branch` (such as from a CI integration) and a ACL policy exists for
`project_1234/env_prod/branch_main`, this could be encoded as:

```
token_policies=["project_{{.project_id}}/env_{{.environment}}/branch_{{.branch}}"]
```

To make this conditional on whether or not the environment is `prod`, one could
encode this as:

```
token_policies=["{{if eq \"prod\" .environment}}project_{{.project_id}}/env_{{.environment}}/branch_{{.branch}}{{end}}"]
```

and this ACL policy would be empty (and thus, removed) if the `environment` claim
on the token used during authentication was `testing` or `staging`.

To reference claims not always present on a token, one can wrap the statement in
an `if` check using the `index` function:

```
{{ if ne nil (index . "optional_claim") }}
... some statement using .optional_claim ...
{{ end }}
```

### Sample payload

```json
{
  "policies": ["dev", "prod"],
  "bound_subject": "sl29dlldsfj3uECzsU3Sbmh0F29Fios1@clients",
  "bound_audiences": "https://myco.test",
  "user_claim": "https://openbao/user",
  "groups_claim": "https://openbao/groups",
  "bound_claims": {
    "department": "engineering",
    "sector": "7g"
  },
  "claim_mappings": {
    "preferred_language": "language",
    "group": "group"
  }
}
```

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/auth/jwt/role/dev-role
```

## Read role

Returns the previously registered role configuration.

| Method | Path                   |
| :----- | :--------------------- |
| `GET`  | `/auth/jwt/role/:name` |

### Parameters

- `name` `(string: <required>)` - Name of the role.

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    https://127.0.0.1:8200/v1/auth/jwt/role/dev-role
```

### Sample response

```json
{
  "data":{
    "bound_subject": "sl29dlldsfj3uECzsU3Sbmh0F29Fios1@clients",
    "bound_audiences": [
      "https://myco.test"
    ],
    "bound_cidrs": [],
    "user_claim": "https://openbao/user",
    "groups_claim": "https://openbao/groups",
    "policies": [
      "dev",
      "prod"
    ],
    "period": 0,
    "ttl": 0,
    "num_uses": 0,
    "max_ttl": 0
  },
  ...
}

```

## List roles

Lists all the roles that are registered with the plugin.

| Method | Path             |
| :----- | :--------------- |
| `LIST` | `/auth/jwt/role` |

### Parameters

 - `after` `(string: "")` - Optional entry to begin listing after for
   pagination; not required to exist.

 - `limit` `(int: 0)` - Optional number of entries to return; defaults
   to all entries.

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    https://127.0.0.1:8200/v1/auth/jwt/role
```

### Sample response

```json
{
  "data": {
    "keys": [
      "dev-role",
      "prod-role"
    ]
  },
  ...
}
```

## Delete role

Deletes the previously registered role.

| Method   | Path                   |
| :------- | :--------------------- |
| `DELETE` | `/auth/jwt/role/:name` |

### Parameters

- `name` `(string: <required>)` - Name of the role.

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    https://127.0.0.1:8200/v1/auth/jwt/role/dev-role
```

## OIDC authorization URL request

Obtain an authorization URL from OpenBao to start an OIDC login flow.

The response will include a `auth_url` that the user will need to go
to in a web browser to complete the login flow.

In device callback mode the response may include a `user_code` keyword
which should be shown to the user to enter at the `auth_url`.

| Method | Path                      |
| :----- | :------------------------ |
| `POST` | `/auth/jwt/oidc/auth_url` |

### Parameters

- `role` `(string: <optional>)` - Name of the role against which the login is being
  attempted. Defaults to configured `default_role` if not provided.
- `redirect_uri` `(string: <required except in device callback mode>)` - Path to the callback to complete the login. This will be
  of the form, "https&#x3A;//.../oidc/callback" where the leading portion is dependent on your OpenBao
  server location, port, and the mount of the JWT plugin. This must be configured with OpenBao and the
  provider. See [Redirect URIs](/docs/auth/jwt#redirect-uris) for more information.
- `client_nonce` `(string: <optional>)` - Optional client-provided nonce that
  must match the `client_nonce` value provided during a subsequent request to the
  [callback](/api-docs/auth/jwt#oidc-callback) API.

### Sample payloads

For client or direct callback modes:

```json
{
  "role": "dev-role",
  "redirect_uri": "https://openbao.myco.com:8200/ui/openbao/auth/jwt/oidc/callback",
  "client_nonce": "ni42i2idj2jj"
}
```

For device callback mode:

```json
{
  "role": "dev-role",
  "client_nonce": "ni42i2idj2jj"
}
```


### Sample request

```shell-session
$ curl \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/auth/jwt/oidc/auth_url
```

### Sample responses

For client or direct callback modes:

```json
{
  "request_id": "c701169c-64f8-26cc-0315-078e8c3ce897",
  "data": {
    "auth_url": "https://myco.auth0.com/authorize?client_id=r3qXcK2bezU3Sbmh0K16fatW6&nonce=851b69a9bfa5a6a5668111314414e3687891a599&redirect_uri=https%3A%2F%2Fopenbao.myco.com3A8200%2Fui%2Fopenbao%2Fauth%2Fjwt%2Foidc%2Fcallback&response_type=code&scope=openid+email+profile&state=1011e726d24960e09cfca2e04b36b38593cb6a22"
  },
  ...
}
```

For device callback mode:

```json
{
  "request_id": "c701169c-64f8-26cc-0315-078e8c3ce897",
  "data": {
    "auth_url": "https://myco.auth0.com/device",
    "user_code": "ABCDEFGHIJK"
  },
  ...
}
```

## OIDC callback

Exchange an authorization code for an OIDC ID Token. The ID token will be further validated
against any bound claims, and if valid an OpenBao token will be returned.

This is normally invoked by the Authorization Server in client
or direct callback modes, and is not used in device callback mode.

| Method | Path                      |
| :----- | :------------------------ |
| `GET`  | `/auth/jwt/oidc/callback` |

### Parameters

- `state` `(string: <required>)` - Opaque state ID that is part of the Authorization URL and will
  be included in the the redirect following successful authentication on the provider.
- `code` `(string: <optional>)` - Provider-generated authorization code that OpenBao will exchange for
  an ID token.  Required if no `id_token` given.
- `id_token` `(string: <optional>)` - If present instead of an authorization code, will be used directly
  instead of exchanging the code to get it.  Required if no `code` given.
- `client_nonce` `(string: <optional>)` - Optional client-provided nonce that must
  match the `client_nonce` value provided during the prior request to the
  [auth_url](/api-docs/auth/jwt#oidc-authorization-url-request) API.
- `error_description` `(string: <optional>)` - Detailed description of an error if there was an error.
  If present, will be included in the error message passed back to the requester.

### Sample request

```shell-session
$ curl \
    https://127.0.0.1:8200/v1/auth/jwt/oidc/callback?state=n2kfh3nsl&code=mn2ldl2nv98h2jl&client_nonce=ni42i2idj2jj
```

### Sample response

```json
{
    "auth":{
        "client_token":"f33f8c72-924e-11f8-cb43-ac59d697597c",
        "accessor":"0e9e354a-520f-df04-6867-ee81cae3d42d",
        "policies":[
            "default",
            "dev",
            "prod"
        ],
        "lease_duration":2764800,
        "renewable":true
    },
    ...
}
```

## OIDC poll

Poll for a response when using the direct or device callback modes in order to complete a login.
The response from the [auth_url](/api-docs/auth/jwt#oidc-authorization-url-request) API
returns a `poll_interval` data item containing the number of seconds that the client
should wait between invoking the poll API.

If the direct callback or device mode authorization hasn't yet occurred,
the HTTP response code will be 400 and include
an `errors` JSON list including either `authorization_pending` or `slow_down`.
If the response is `slow_down` then the client should add additional time before
calling the poll API again.

When the callback or authorization has occurred, the response will include either a different `errors`
message or sucessfully return an authorization token.

| Method | Path                      |
| :----- | :------------------------ |
| `GET`  | `/auth/jwt/oidc/poll` |

### Parameters

- `state` `(string: <required>)` - Opaque state ID that was part of the Authorization URL
  and must match the state returned from the OIDC provider.
- `client_nonce` `(string: <optional>)` - Optional client-provided nonce that must
  match the `client_nonce` value provided during the prior request to the
  [auth_url](/api-docs/auth/jwt#oidc-authorization-url-request) API.

### Sample payload

```json
{
  "state": "n2kfh3nsl",
  "client_nonce": "ni42i2idj2jj"
}
```

### Sample request

```shell-session
$ curl \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/auth/jwt/oidc/poll
```

### Sample responses

When response hasn't yet occurred:

```json
{
  "errors": [
    "authorization_pending"
  ]
}
```

On success:

```json
{
    "auth":{
        "client_token":"f33f8c72-924e-11f8-cb43-ac59d697597c",
        "accessor":"0e9e354a-520f-df04-6867-ee81cae3d42d",
        "policies":[
            "default",
            "dev",
            "prod"
        ],
        "lease_duration":2764800,
        "renewable":true
    },
    ...
}
```

## JWT login

Fetch a token. This endpoint takes a signed JSON Web Token (JWT) and
a role name for some entity. It verifies the JWT signature to authenticate that
entity and then authorizes the entity for the given role.

| Method | Path              |
| :----- | :---------------- |
| `POST` | `/auth/jwt/login` |

### Parameters

- `role` `(string: <optional>)` - Name of the role against which the login is being
  attempted. Defaults to configured `default_role` if not provided.
- `jwt` `(string: <required>)` - Signed [JSON Web Token](https://tools.ietf.org/html/rfc7519) (JWT).

### Sample payload

```json
{
  "role": "dev-role",
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

### Sample request

```shell-session
$ curl \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/auth/jwt/login
```

### Sample response

```json
{
    "auth":{
        "client_token":"f33f8c72-924e-11f8-cb43-ac59d697597c",
        "accessor":"0e9e354a-520f-df04-6867-ee81cae3d42d",
        "policies":[
            "default",
            "dev",
            "prod"
        ],
        "lease_duration":2764800,
        "renewable":true
    },
    ...
}
```
